Skip to content

feat(audit): make audit records tamper-evident and queryable - #142

Open
woahwhattheheck wants to merge 1 commit into
RemitFlow:mainfrom
woahwhattheheck:latch/remitflow-127-audit-integrity
Open

feat(audit): make audit records tamper-evident and queryable#142
woahwhattheheck wants to merge 1 commit into
RemitFlow:mainfrom
woahwhattheheck:latch/remitflow-127-audit-integrity

Conversation

@woahwhattheheck

@woahwhattheheck woahwhattheheck commented Sep 24, 2026

Copy link
Copy Markdown

Closes #127

Problem

Sensitive transfer investigations are unreliable if audit records can be changed silently or cannot be correlated to a request.

What this PR does

Acceptance criterion How it is met
Tampering is detectable Each entry carries chainSeq, prevHash, and entryHash (SHA-256 over a canonical payload). verifyIntegrity() / GET /api/audit/integrity recomputes the chain.
Every privileged mutation has one outcome event Create / claim / cancel / archive / unarchive / user-create emit a single outcome: success event. Retries with the same (action, target, correlationId, outcome) return the existing entry instead of appending.
Authorized operators can filter without exposing secrets GET /api/audit remains behind audit:read. New filters: action, scope, outcome, correlationId, actor. Changes are redacted at write; actors are HMAC fingerprints, never raw tokens.

Design tradeoffs

  • Hash chain over Merkle trees / external anchoring. Enough to detect silent in-process edits for the in-memory store without inventing a persistence layer the rest of the app does not have.
  • Dedup keyed by correlation id. Without a correlation id, appends remain unrestricted so internal/test callers are unchanged. With one, a retried mutation cannot inflate the trail.
  • Actor fingerprints, not raw tokens. Operators can still filter by who acted; captured audit responses cannot be used to recover API tokens.
  • Compat aliases kept. resourceId / requestId / payload continue to work alongside target / correlationId / changes.

Compatibility impact

  • Additive fields on audit entries and additive query params on GET /api/audit.
  • New route: GET /api/audit/integrity (audit:read).
  • Archive / unarchive now write audit events (previously silent).
  • Optional env: AUDIT_ACTOR_SECRET (falls back to PAGINATION_CURSOR_SECRET).

Tests

test/auditIntegrity.test.js covers:

  • Integrity-chain linking and clean verification
  • REGRESSION: silent field edit breaks the chain
  • REGRESSION: broken prevHash is detected
  • Redaction of nested secrets at rest and over HTTP
  • Duplicate-event suppression (including transfer-create retry)
  • Query authorization (401 / 403 / integrity scope)
  • Correlation / scope / actor filters without leaking tokens
  • Archive / unarchive each emit one outcome event

Verification

npm test
# tests 270
# pass  270
# fail  0

Baseline on upstream/main was 256. No unrelated tests were skipped, deleted, or weakened.

Out of scope

  • External blockchain anchoring or durable disk WAL
  • Broad rewrites of unrelated services or user flows

@woahwhattheheck
feat(audit): make audit records tamper-evident and queryable
557a2ba 
Add hash-chained integrity metadata, redacted attribution fields, duplicate
outcome suppression, and authorized filters so transfer investigations can
detect silent tampering and correlate privileged mutations without exposing
secrets.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

security(backend): make audit records tamper-evident and queryable

1 participant

@woahwhattheheck